Aperture Photometry¶

The agilepy AGAnalysis class can be used not only for Maximum Likelihood analysis, but also for an Aperture Photometry analysis.

The Aperture Photometry provides the exposure and counts of an ON region.

In [1]:
# Import the relevant classes
from agilepy.api.AGAnalysis import AGAnalysis
from agilepy.utils.AstroUtils import AstroUtils

from astropy.coordinates import SkyCoord
from astropy.table import Table
from astropy.time import Time

Setup¶

This tutorial uses the available test dataset on blazar 3C 454.3, from 2010-11-13 to 2010-11-21 (MJD 55513-55521).

In [2]:
# Prepare the YAML Configuration File.
# You can create it manually or use AGVisibility.getConfiguration()

outputDir    = "/home/flareadvocate/workspace/shared_dir/"
confFilePath = "/home/flareadvocate/workspace/shared_dir/tutorial_ap.yaml"

AGAnalysis.getConfiguration(
    confFilePath = confFilePath,
    # Output
    outputDir = outputDir,
    userName = "my_name",
    sourceName = "3C454_3",
    verboselvl = 0,
    # Input
    evtfile="$AGILE/agilepy-test-data/test_dataset_agn/EVT/EVT.index",
    logfile="$AGILE/agilepy-test-data/test_dataset_agn/LOG/LOG.index",
    userestapi=False,
    # Selection
    tmin = 55513.0,
    tmax = 55521.0,
    timetype = "MJD",
    glon = 86.11,
    glat = -38.18,
)
In [3]:
# Create the AGAnalysis object
ag = AGAnalysis(confFilePath)

# Update General Options
ag.setOptions(binsize=0.5, expstep=2, mapsize=25)
ag.setOptions(energybins=[[100, 50000]])

# Update Aperture Photometry Options: Radius, Timeslot
ag.setOptions(radius=2)       # ON region radius
ag.setOptions(timeslot=10800) # Bin size for the Light Curve

# Check Aperture Photometry configuration
ag.printOptions("ap")

Log level set to WARNING and output to /home/flareadvocate/workspace/shared_dir/my_name_3C454_3_20251013-142701/logs
{'radius': 2, 'timeslot': 10800}
In [4]:
# Check General configuration
ag.printOptions()

{ 'ap': {'radius': 2, 'timeslot': 10800},
  'input': { 'datapath': 'None',
             'evtfile': '/home/flareadvocate/agiletools/agilepy-test-data/test_dataset_agn/EVT/EVT.index',
             'logfile': '/home/flareadvocate/agiletools/agilepy-test-data/test_dataset_agn/LOG/LOG.index',
             'userestapi': False},
  'maps': { 'binsize': 0.5,
            'energybins': [[100, 50000]],
            'expstep': 2,
            'fovbinnumber': 1,
            'mapsize': 25,
            'offaxisangle': 30,
            'proj': 'ARC',
            'projtype': 'WCS',
            'spectralindex': 2.1,
            'timestep': 160,
            'useEDPmatrixforEXP': False},
  'mle': { 'contourpoints': 40,
           'edpcorrection': 1,
           'expratio_maxthr': 15,
           'expratio_minthr': 0,
           'expratio_size': 10,
           'expratioevaluation': True,
           'fluxcorrection': 0,
           'integratortype': 1,
           'loccl': 5.99147,
           'mindefaulttolerance': 0.01,
           'minimizeralg': 'Migrad',
           'minimizerdefstrategy': 2,
           'minimizertype': 'Minuit',
           'ranal': 10,
           'ulcl': 2},
  'model': { 'galcoeff': [-1],
             'galmode': 1,
             'galmode2': 0,
             'galmode2fit': 0,
             'isocoeff': [-1],
             'isomode': 1,
             'isomode2': 0,
             'isomode2fit': 0,
             'modelfile': None},
  'output': { 'filenameprefix': 'analysis_product',
              'outdir': PosixPath('/home/flareadvocate/workspace/shared_dir/my_name_3C454_3_20251013-142701'),
              'sourcename': '3C454_3',
              'username': 'my_name',
              'verboselvl': 0},
  'plotting': {'twocolumns': False},
  'selection': { 'albedorad': 80,
                 'bpointing': None,
                 'dq': 0,
                 'filtercode': 5,
                 'fovradmax': 60,
                 'fovradmin': 0,
                 'glat': -38.18,
                 'glon': 86.110001,
                 'irf': 'H0025',
                 'lonpole': 180,
                 'lpointing': None,
                 'maplistgen': 'None',
                 'phasecode': 6,
                 'proj': 'ARC',
                 'timelist': 'None',
                 'timetype': 'TT',
                 'tmax': 217382400.0,
                 'tmin': 216691200.0}}

Execution¶

The function AGAnalysis.aperturePhotometry() calls the AGILE Tool which compute the Aperture Photometry light curve.

The output file is a text file (columns separated by whitespaces) providing four columns:

  • Minimum maximum time of each bin in AGILE seconds
  • Maximum maximum time of each bin in AGILE seconds
  • ON region Exposure in cm*2s
  • ON region Counts

The AperturePhotometry Table can be retrieved as an astropy.table.Table object using AGAnalysis.lightCurveTable.

In [5]:
# Run Aperture Photometry Tool
lightCurveData, _ = ag.aperturePhotometry()

# Output file
print(lightCurveData)

/home/flareadvocate/workspace/shared_dir/my_name_3C454_3_20251013-142701/ap/analysis_product
In [6]:
# The output table is stored in:
ap_table = ag.lightCurveTable['ap']
display(ap_table)
Table length=64
tmin_TTtmax_TTexposurecounts
float64float64float64int64
216691200.0216702000.0337800.790
216702000.0216712800.0361067.90
216712800.0216723600.0564908.662
216723600.0216734400.0524760.41
216734400.0216745200.0532771.081
216745200.0216756000.0434508.262
216756000.0216766800.0370341.091
216766800.0216777600.0443719.821
216777600.0216788400.0381544.551
216788400.0216799200.0395535.562
............
217274400.0217285200.0432209.8412
217285200.0217296000.0334224.325
217296000.0217306800.0352824.5713
217306800.0217317600.0261572.177
217317600.0217328400.0592315.7111
217328400.0217339200.0644026.9819
217339200.0217350000.0553286.417
217350000.0217360800.0447504.027
217360800.0217371600.0369263.817
217371600.0217382400.0393622.248
In [7]:
# The AstroUtils class offers a function to convert AGILE seconds to other formats:
time_min = AstroUtils.convert_time_from_agile_seconds(ap_table['tmin_TT'])

# Print e.g in MJD
display(time_min.mjd)

array([55513.   , 55513.125, 55513.25 , 55513.375, 55513.5  , 55513.625,
       55513.75 , 55513.875, 55514.   , 55514.125, 55514.25 , 55514.375,
       55514.5  , 55514.625, 55514.75 , 55514.875, 55515.   , 55515.125,
       55515.25 , 55515.375, 55515.5  , 55515.625, 55515.75 , 55515.875,
       55516.   , 55516.125, 55516.25 , 55516.375, 55516.5  , 55516.625,
       55516.75 , 55516.875, 55517.   , 55517.125, 55517.25 , 55517.375,
       55517.5  , 55517.625, 55517.75 , 55517.875, 55518.   , 55518.125,
       55518.25 , 55518.375, 55518.5  , 55518.625, 55518.75 , 55518.875,
       55519.   , 55519.125, 55519.25 , 55519.375, 55519.5  , 55519.625,
       55519.75 , 55519.875, 55520.   , 55520.125, 55520.25 , 55520.375,
       55520.5  , 55520.625, 55520.75 , 55520.875])
In [8]:
# Plot Light Curve
ag.displayLightCurve("ap", saveImage=False)
In [9]:
# Save Light Curve Plot
lc_plot = ag.displayLightCurve("ap", saveImage=True)

print(f"Plot saved in: {lc_plot}")

Plot saved in: /home/flareadvocate/workspace/shared_dir/my_name_3C454_3_20251013-142701/plots/light_curve_216702000.0_217382400.0.png
In [ ]: